home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 November: Tool Chest / Dev.CD Nov 96 TC / Dev.CD Nov 96 TC.toast / Sample Code / Snippets / Sound / SndPlayDoubleBuffer / Read Me - SimpleQT.doc next >
Encoding:
Text File  |  1996-05-06  |  6.4 KB  |  142 lines  |  [TEXT/CWIE]
  1. /*                                Read Me for SimpleApp Sound
  2.  
  3. The primary purpose of this sample code is to show developers how to use SndPlayDoubleBuffer
  4. to play AIFF, WAVE, and .au files asynchronously from disk.
  5.  
  6. To this end this sample can be used to show you how to:
  7.  
  8. 1) parse an AIFF, 'snd ' resource, WAVE, or .au header
  9. 2) use PBReadAsync() at interrupt time
  10. 3) munge AIFF, WAVE, and .au data into a form the Sound Manager can play
  11. 4) set up the sound header to play compressed and uncompressed sounds
  12. 5) instantly (well, really quickly) pause a sound
  13. 6) stop a sound so you can play from some other part of the sound
  14. 7) make it sound like you are playing a sound backwards
  15. 8) use completion routines
  16. 9) have fun with sounds
  17.  
  18.  
  19. --Features--
  20.  
  21. SimpleApp
  22.  
  23. This code was developed using fellow DTS engineer (and really cool guy) Matt Mora's SimpleApp
  24. framework.
  25.  
  26. This simple framework hides the dirty work of the Mac interface allowing me (and you) to
  27. concentrate on the code that is actually doing the interesting work.
  28.  
  29. AIFC
  30. ----
  31.  
  32. It can play AIFC files compressed with µlaw, IMA, MACE 3:1 and MACE 6:1, it should be able to
  33. play other formats if the proper decompressor is installed, but I have only tested with these
  34. four decompressors.
  35.  
  36. IMA is a run length compression, and as such you cannot play an IMA compressed sound backwards,
  37. or use random access within a file using the simple techniques I use in this example.  It should
  38. disable the scroll bar when playing an IMA compressed sound, but it currently doesn't.  If you
  39. do jump around in an IMA compressed file, the really bad noises you hear are normal.  Just stop
  40. the sound if you get tired of hearing them.
  41.  
  42. AIFF
  43. ----
  44.  
  45. It can play all AIFF files (that I know of) without a problem.
  46.  
  47. 'snd ' resources
  48. ----------------
  49.  
  50. It can play all the 'snd ' resources that I have seen.  I have not done extensive testing
  51. on these yet, but they work well enough so far.  I would like to add the ability to play
  52. all the 'snd ' resources inside of a resource file, but currently it only plays the first
  53. 'snd ' resource that it finds.
  54.  
  55. It does not play 'snd ' resources that are not sampled-sound data, and it does not play
  56. 'snd ' resources that have multiple commands (i.e. multiple tracks), but I haven't seen
  57. any of these files to test with either.
  58.  
  59. Playing a 'snd ' resource isn't as easy at would seem.  Since this is a SndPlayDoubleBuffer()
  60. example I am not reading in the entire 'snd ' resource into memory as some other examples do.
  61. Since I have to fill SndPlayDoubleBuffer() buffers' at interrupt time, using the Resource
  62. Manager is out as well.  I have written some _VERY_ basic functions that will open a resource
  63. fork, read in the header, look around and get the information I need.  In this way I am able
  64. to use PBReadAsync() at interrupt time to read more of the 'snd ' resource.
  65.  
  66. If you wish to use this resource code, feel free, but make sure you test it thoroughly.  It
  67. works for me, but I can't say that it does everything, or that it does what it does, in all
  68. cases, correctly.
  69.  
  70. .snd and .au files
  71. ------------------
  72.  
  73. I have added Sun/NeXT .snd support (better known as .au sounds).  Currently it can play
  74. 8 and 16 bit linear (non-compressed) sounds and µlaw compressed files.  The other file
  75. formats don't seem to be too popular (I haven't been able to find one), and it doesn't
  76. look like the Sound Manager would support them (like 24 and 32 bit linear) even if I found
  77. them.
  78.  
  79. WAVE
  80. ----
  81.  
  82. It can play PCM (Pulse Code Modulation) and µlaw WAVE files, it can not play ADPCM or IMA
  83. compressed WAVE files.  IMA compressed WAVE files have a different data stream than an IMA
  84. compressed AIFF file and the IMA decompressor cannot handle it.  I do not think I will ever
  85. be able to make IMA compressed WAVE files play without a new IMA decompressor that can
  86. handle this different format.
  87.  
  88. The endian conversion code has been written in C and both 68K and PowerPC assembly (because
  89. I wanted to) so WAVE files will work on both 68K and PPC Macs, but they should require less
  90. interrupt resources on a Power Mac because the PPC assembly makes use of the (really cool)
  91. store byte reversed command to make the processor do all the real endian conversion.  Using
  92. this command the assembly version of the routines are about the same size, or smaller than
  93. their C versions.  I have not unrolled the PPC assembly because I didn't feel there was too
  94. much speed to be gained (though I did no actuall testing).  This is left as an exercise for
  95. the reader (I've always wanted to say that).
  96.  
  97. Note:
  98. If you do random access inside of a WAVE file you may get garbage played for an instant.
  99. I have not tracked down where this is coming from, and it doesn't happen all the time.  I'm
  100. working on finding the cause of this.
  101.  
  102.  
  103. --Background--
  104.  
  105. When I first started this sample I was hoping for something similar to MoreFiles, well that
  106. didn't happen.  But the routines in DoubleBufferFromFile.c, Private_DBFFFunctions.c,
  107. and Interrupt_Routines.c are still pretty useful.  I tried to make them as simple and self-
  108. sufficient possible.  You will find, however, that it is a somewhat complicated process to
  109. fill in the data required to start playing an AIFF, 'snd ' resource, WAVE, or .au file so
  110. those routines work more as a package, but I think it is a good start.
  111.  
  112. I hope to have made the code largely self explanitory, with comments where necessary.
  113.  
  114. As always, I welcome your feedback (good or bad).  I can be reached at mcookson@apple.com.
  115. Please let me know what you find useful, what you find not useful, and what you would like
  116. to see in a future example of this type.
  117.  
  118.  
  119. --Known bugs--
  120.  
  121. The only bug that I am aware of (beside the problem with the WAVE garbage) is that if you
  122. do random access within a sound, the stereo tracks are likely to get reversed.  I may fix
  123. this, I haven't decided yet.
  124.  
  125.  
  126. --Disclaimer--
  127.  
  128. The Sound Manager currently does not directly support WAVE or .au/.snd files like it does
  129. 'snd ' and AIFF/AIFC files.  Sound Manager 3.2 does have an endian decompressor for WAVE
  130. files, but I do not use it.  The Sound Manager does not directly read or parse .au/.snd
  131. or WAVE file's headers.  The code I have has been written based on the file format information
  132. that I have found on World Wide Web and the few files that I have been able to make or
  133. find.  This code is probably no where near complete, make sure you test it with the sounds
  134. you want to play to make sure that it works before you include this code in a real product.
  135.  
  136.  
  137. Happy coding,
  138. Mark Cookson
  139. Developer Technical Support
  140. Apple Computer, Inc.
  141.  
  142. */